Generating Serial Numbers Dynamically

SoftwareShield CheckPoint™ License Server > CheckPoint License Server Interfaces > HTTP GET URL Interface > Generating Serial Numbers Dynamically

### Generating Serial Numbers Dynamically
(through the HTTP GET Interface)

Before you read this section, be sure you are familiar with the basic HTTP GET Interface concepts.

Probably the easiest way to program against the HTTP GET Interface is to construct prototypes of the URL's you will dynamically produce and call them directly through a browser. The Checkpoint License Server will deliver the responses right into the browser in a readable format and once you have a methodology figured out - you can move to your code and test it programmatically.

When you wish to generate Serial Numbers dynamically, you will always use the "nsn" action in the path of the URL you construct (see "Component C").

Be sure to use a valid CheckPoint Administrators credentials in the path as well, right after the action portion. (see "Component D"). Note that they must be passed as <user name>*<password> (separated by an asterisk).

### Parameters

There are a number of parameters you can use to dynamically generate a new Serial Number. They are:

Default Query Parameter Name | Map-able to a different Name | Required or Optional | Description
GSNLIC |  | Required | The License ID on the server you wish to generate the Serial Number for.
GSNAID |  | Required | The Authorization Definition ID inside the license you wish to generate the Serial Number for.
GSNPno |  | Required * | The numeric parameter you wish to use for activations associated with this Serial Number.
GSNPdt |  | Required * | The date parameter you wish to use for activations associated with this Serial Number. (In Universal Time Coordinated [UTC])
GSNTEM |  | Optional | The Return Template ID you wish to use to format responses from the server.
GSNPAC |  | Optional | The number of Permitted Activations you wish to allow for this Serial Number. (defaults to 1 if not provided).
GSNPOAC |  | Optional | The number of Overflow Activations you wish to allow for this Serial Number. (defaults to 0 if not provided).
GSN * * |  | Optional | This is a special parameter that allows you to compress multiple other URL Encoded parameters in this list into a single parameter value (see below).
QPM * * * |  | Optional | Query string parameter name mapping ID that you wish to use to map default query parameter names in this list into your own names.
CPEUNAME * * * * |  | Optional | CheckPoint End User Name that you wish to use to associate with this Serial Number.
CPEUCONM * * * * |  | Optional | CheckPoint End User Company Name that you wish to use to associate with this Serial Number.
CPEUREF * * * * |  | Optional | CheckPoint End User Referrer that you wish to use to associate with this Serial Number.
CPEUIP * * * * |  | Optional | CheckPoint End User IP address that you wish to use to associate with this Serial Number.
CPEUA1 * * * * |  | Optional | CheckPoint End User Address field 1 that you wish to use to associate with this Serial Number.
CPEUA2 * * * * |  | Optional | CheckPoint End User Address field 2 that you wish to use to associate with this Serial Number.
CPEUA3 * * * * |  | Optional | CheckPoint End User Address field 3 that you wish to use to associate with this Serial Number.
CPEUPH * * * * |  | Optional | CheckPoint End User Phone Number that you wish to use to associate with this Serial Number.
CPEUEM * * * * |  | Optional | CheckPoint End User Email address that you wish to use to associate with this Serial Number.
CPEUPW * * * * |  | Optional | CheckPoint End User Password that you wish to use to associate with this Serial Number.
CPONO * * * * * |  | Optional | Order number from an external system.

* Serial Number Generation Parameter Value Notes

The GSNPno parameter is required if no date parameter (GSNPdt) is supplied. Conversely, the GSNPdt parameter is required if no date parameter (GSNPno) is supplied.

If the Authorization Definition that you are generating a Serial Number for does not take a date type parameter you must specify GSNPno. If the definitions parameter value has no meaning to you or is not used directly, you must still pass GSNPno - but may specify a zero (0) value.

When specifying a date type parameter you must use the format: yy-mm-dd, where yy specifies the year after the year 2000. Example, to specify June 21, 2010, you must pass "10-06-21". Note that the date will be interpreted as Universal Time Coordinated [UTC].

* * GSN parameter

The GSN parameter (Generate Serial Number) is a special parameter for your use when you do not have control over a third party caller of your HTTP interface (like a merchant services provider) and you only have access to one free form parameter. You can effectively pass any number of other parameters inside the GSN parameter.

NOTE: If you have control over the parameters passed to the CheckPoint License Servers HTTP Interface (you are writing the caller) - you do not have to use a GSN parameter. In this case it is recommended that you do not use a GSN parameter because it unnecessarily complicates things.

Parameters which you may pass inside the GSN parameter value include all the other parameters shown above except those for end-user details (if necessary, these can be "mapped", see below).

In order to embed other parameter values inside the GSN parameter you must URL encode them. Most libraries have the functionality to perform URL encoding for you. However it can be done "manually" if you need. The two most important characters that you must URL Encode are "=" and "&" which are the delimiters for query string parameters. These, when URL Encoded convert to "%3D" and "%26" respectively.

#### Example of how to use the GSN Parameter

Lets say you use a merchant services provider (like Kagi®, SWREG® or Digital River®) to sell your software. These providers do allow you to call a web-deployed program to generate "keys" (Serial Numbers) for your software when they sell a copy. However, they often only provide a single free-form parameter that you can specify an arbitrary value in as input to this program.

Now, you want to call the CheckPoint License Server to generate a Serial Number for your client as the result of a sale by the merchant services provider. But, you only have access to one parameter - and you are required by the CheckPoint server to pass several (GSNLIC,GSNAID,GSNPno or GSNPdt). So, you can pass these parameters inside the GSN parameter.

So, lets say you want to pass the following query string to generate a Serial Number: License ID = 2, Authorization Definition ID = 32, numeric parameter value = 0. Therefore, you would like to pass:

GSNLIC=2&GSNAID=32&GSNPno=0

But - you only have access to one free-form parameter. So you URL Encode the above query string and use it as the value in the GSN parameter like this:

GSN=GSNLIC%3D2%26GSNAID%3D32%26GSNPno%3D0

Notice that above, the "=" has been converted to "%3D" and "&" = "%26". This allows you to pass multiple parameters embedded inside the GSN parameter.

* * * QPM parameter (Query Parameter Mapping)

Note that in the above example (Example of how to use the GSN Parameter), you could also "re-name" the free form parameter to anything you needed. For example if the third party only gave you one free-form parameter value to use and it would always be passed as "user_text" you could simply "map" the parameter name "GSN" to "user_text".

Query parameter mapping is covered in more detail in Map CheckPoint HTTP GET Query Parameters.

* * * * End User Details

End user details are optional when dynamically generating a Serial Number. However, if you do not pass any details, no end-user is associated with the Serial Number at generation time. If ANY information is passed in any one of these parameters, an end-user record will be created.

* * * * * Order Number

The order number is optional when dynamically generating a Serial Number. This is an order number from an external system (like your merchant services provider). This order number (if passed) will be associated with the generation of this Serial Number (for tracking, reporting and auditing purposes).

#### Examples Calls to Dynamically Generate a Serial Number:

Because of the length of some of these examples, we have dropped components "A", "B", "C" and "D" and only show component "E" (the parameters). For a review of what the components of the URL are, please see: HTTP GET URL Interface.

In all these examples you can assume that the remainder of the URL shown is prefixed by the HTTP path and application name in exactly the same way (for example they all start with: "https://secure.server.com/cp/checkpoint.dll/nsn/admin*password")

- This call generates a new Serial Number for License ID = 0, Authorization Definition ID = 1, Numeric Parameter = 9876, using Return Template ID = 3, with 55 Activations Permitted and 4 Overflow Activations Permitted. No user information is passed, so no user will be associated with the generation of this Serial Number. This is the kind of call you might make if you have total control over the number and names of parameters you can pass.
  ?GSNLIC=0&GSNAID=1&GSNPno=9876&GSNTEM=3&GSNPAC=55&GSNPOAC=4

- This call uses the special GSN parameter to contain the other query parameter names and values. Note that inside the GSN parameter we pass exactly the same parameters as the call above - but as the GSN value. Also, notice that the contained parameters are URL encoded. This is the kind of call you might make if you have control over the name of the free-form parameter, but not the number available (you have only one).
  ?GSN=GSNLIC%3D0%26GSNAID%3d1%26GSNPno%3d9876%26GSNTEM%3d3%26
  GSNPAC%3d55%26GSNPOAC%3d4

- This call is the exact same as above, except we have passed user information to associate with the Serial Number generated:
  ?CPEUNAME=Carlos LastName&CPEUCONM=Co. Name Ltd.&CPEUA1=Add 1&
  CPEUA2=Add 2&CPEUA3=Add 3&CPEUPH=604-111-5555&CPEUEM=jhgsdf@bndf.com&
  CPEUREF=REFERRER453&CPEUIP=24.114.114.114&GSN=GSNLIC%3D0%26
  GSNAID%3d1%26GSNPno%3d9876%26GSNTEM%3d3%26GSNPAC%3d55%26
  GSNPOAC%3d4
- This call is the same as the one above, however, the parameter names have been "mapped". Note that the parameter names are not the default parameter names (they all end in "2"). The exception is the embedded parameter names (inside the GSN parameter which is itself mapped to "GSN2") These mappings were used because we also passed (as an embedded parameter QPM=2). Query Parameter Mapping ID 2 in the database is used to map the names before the query is parsed. Lastly, notice that some optional user parameters were omitted (address 3). This is the kind of call you might make if you have no control over the name of the free-form parameter, and you have only one.:
  ?CPONO2=U1234567&CPEUNAME2=Carlos LastName&CPEUCONM2=Co. Name Ltd.&
  CPEUA12=Add 1&CPEUA22=Add 2&CPEUPH2=604-111-5555&CPEUEM2=jhgsdf@bndf.com&
  CPEUREF2=REFERRER453&CPEUIP2=24.114.114.114&GSN2=GSNLIC%3D0%26
  GSNAID%3d1%26GSNPno%3d9876%26GSNTEM%3d3%26GSNPAC%3d55%26
  GSNPOAC%3d4%26QPM%3d2

Note: The SoftwareShield CheckPoint™ License Server only comes with the Server Edition of the SoftwareShield System.